NGLister 2.0 Definition File Format
Format Version 1
(c)2005 JF Software
Joshua Foster / ShittyKitty
http://www.jfsoftware.com

(NOte: This document looks better with Word Wrap turned OFF!)

DESCRIPTION
===========
This file describes the formatting of the NGLister Definition File (.ngl).  The current
Format Version described in this document is Format Version 1.

NOTES
=====
* Use the nglister.ngl file in the NGLister program's folder as a reference while using
  this document.  Make sure to keep a backup, however, if you decide to make changes.
* In a Definition File (known as a "def file" from here on out), each piece of information
  is placed on its own line.
* Unless otherwise noted, all grabbers are used on the "Profile URL" specified in the
  Header.
* Lines that contain N indicate a repeated set of lines.
* Use  to indicate a line return inside a string.
* Use  to indicate the user's number inside a string.
* Use  to indicate the page number for the review URL.
* Make sure there is always an extra line between the Cutoff and Grabbers sections, and
  between each individual grabber.
* You can put anything you want in the extra lines indicated with (Blank Line); anything in
  these lines is ignored by the program.
* You can also put anything you want before the first Header line.  Anything before the
  first Header line (NGLISTERDEFXXXYYY) is ignored by the program.

BASIC LAYOUT
============
There are three sections to a def file:

* Header - Contains version info and exist string
* Cutoff - Contains strings for above-below profile cutoff
* Grabbers - Descriptions for each grabber
             Consists of two parts:
             * GRABBER - GLOBAL and a GRABBER - XXXX (where XXXX is the grabber type)

HEADER SECTION
==============
Line Name		Notes
-------------------------------------------------------------------------------------------
Definition Version	* Must be NGLISTERDEFXXXYYY, where XXX is the format number (when
			  using this document, this will be 001) and YYY is the version
			  number (the first definition file is 001)
			* Please be sure to never use an old version number for a new
			  def file
Author Name
Author Contact Info
Modification Timestamp
Profile URL		* Use  to represent the user's number
Reviews URL		* Use  to represent the user's number
			* Use  to represent the page number
Existence String	* This string is used to determine profile existence (i.e.
			  something that only appears in valid profiles)

CUTOFF SECTION
==============
To enhance accuracy in the NGLister program, grabbers are placed into two categories.  The
first category contains grabbers with search strings that are rather precise, and can be
safely used on the entire profile.  The second category contains search strings that are
less precise, and are better used after trimming highly user-editable parts of the profile.
This section defines how the profile is trimmed for this second category.

Line Name		Notes
-------------------------------------------------------------------------------------------
Number of Strings
String N		* As described in the NOTES section above, any line containing N
			  indicates that this is a repeated set of lines.  In this case,
			  that means that there will be multiple "String" lines and
			  multiple "Cutoff Type" lines, grouped in pairs.
Cutoff Type N		* This line describes how the profile is cut.  There are two
			  possible values:
			  * BEF
			    Remove everything in the profile BEFORE this string.
			  * AFT
			    Remove everything in the profile AFTER this string.
(Blank Line)		* This indicates that a blank line MUST be left here.  As described
			  in the NOTES section above, however, you can put anything you
			  want here to enhance the separation, and the program will ignore
			  it.

GRABBERS SECTION
================
This section contains the description of each grabber.  A grabber consists of two parts:

* GRABBER - GLOBAL
  This contains information for every grabber type
* GRABBER - XXXX
  Grabber type-specific info, where XXXX is one of the following grabber types:
  * PULL (straight pull)
    Pull the information straight from the profile.
  * CNTR (counter)
    Count the number of occurences of a certain string.
  * REPL (replace pull)
    Same as a PULL grabber, but conditionally replaces the pulled value.
  * ADDN (add numbers)
    Adds two or more grabber values together.
  * RRPL (review response pull)
    Special type used for the Review Response grabber.
  * RRRP (review response rate pull)
    Special type used for the Review Response Rate grabber.  If you use this, you MUST also
    have a grabber for Review Count and an RRPL grabber for Review Responses.

GRABBER - GLOBAL
================
Line Name		Notes
-------------------------------------------------------------------------------------------
Title			* This is shown next to the grabber's checkbox in the NGLister user
			  interface
Abbreviation		* Used for identification and for the default output filename
			* Typically all lowercase
Variable Type		* A grabber can pull data as one of three types (three possible
			  values for this line):
			  * STR (string)
			    A series of characters (letters and numbers)
			  * INT (integer)
			    A number that doesn't contain a decimal point
			  * DEC (decimal)
			    A number that does contain a decimal point.  By default, this
			    rounds to 2 decimal places.  To round to a different amount,
			    add the number of places to the end of this line.  For example,
			    putting DEC3 here will round to three decimal places.
			* For information on grabber type-variable type compatibility, see
			  the "Accepted Variable Types" sections in each GRABBER - XXXX
			  section of this document
Default Value		* This value is used if nothing is found in the profile
			* Leaving this line blank will use a 0 or empty string
			* Type an asterisk (*) in this line to use the "empty profile" data
			  set by the user
Cutoff Position		* Two possible values:
			  * 0
			    Use this grabber BEFORE the profile cutoff
			  * 1
			    Use this grabber AFTER the profile cutoff
			* For more information on profile cutoff, see the CUTOFF SECTION
			  section above
Grabber Type		* Six possible values, as described in the GRABBERS SECTION section
			  above:
			  * PULL
			    Straight pull
			  * CNTR
			    Counter
			  * REPL
			    Replace pull
			  * ADDN
			    Add numbers
			  * RRPL
			    Review response pull
			  * RRRP
			    Review response rate pull

GRABBER - PULL
==============
Accepted Variable Types
-----------------------
* STR
* INT
* DEC

Line Name		Notes
-------------------------------------------------------------------------------------------
Search String		* The string that comes before the targeted data
			* Make this as precise as possible!
End String		* The string that comes immediately after the targeted data
			* This doesn't need to be precise, because it uses the first
			  occurence AFTER the Search String
(Blank Line)

GRABBER - CNTR
==============
Accepted Variable Types
-----------------------
* INT

Line Name		Notes
-------------------------------------------------------------------------------------------
Initial Search String	* The string that comes before the to-be-counted occurences
			* This string must only occur once, and be precise!
Occurence String	* This string is counted, and only after the Initial Search String
			  and before the End String
End String		* This doesn't need to be immediately after the occurences, just as
			  long as it's before occurences that will not be counted
(Blank Line)

GRABBER - REPL
==============
Accepted Variable Types
-----------------------
* STR

Line Name		Notes
-------------------------------------------------------------------------------------------
Search String		* The string that comes before the targeted data
			* Make this as precise as possible!
End String		* The string that comes immediately after the targeted data
			* This doesn't need to be precise, because it uses the first
			  occurence AFTER the Search String
Number of Replacements
Search String N		* The program checks to see if the pulled data matches this string
			* To define an "else" situation (none of the search strings match
			  the pulled data), leave this line blank (you can only do this
			  once per grabber!)
Replace String N	* If the pulled data matches the Search String attached to this
			  Replace String (or if the data doesn't match anything and the
			  attached Search String is empty), the program uses this string
(Blank Line)

GRABBER - ADDN
==============
Accepted Variable Types
-----------------------
* INT
* DEC

Notes
-----
* Make sure you define ADDN-type grabbers *after* defining the referenced grabbers.
* Any grabbers referenced by an ADDN-type grabber MUST be INT or DEC.  STR grabbers can not
  be added together, and the program will not accept the def file.
* The NGLister interface will "lock" any grabbers referenced by an ADDN-type grabber, when
  the ADDN-type grabber is active.  This ensures that the ADDN-type grabber will have data
  to add.

Line Name		Notes
-------------------------------------------------------------------------------------------
Number of Values
Abbrev. for Grabber N	* This is the "Abbreviation" line from the GLOBAL section of each
			  grabber you wish to add together
			* If a referenced grabber doesn't exist, the program will reject
			  the def file
(Blank Line)

GRABBER - RRPL
==============
Accepted Variable Types
-----------------------
* INT

Notes
-----
* RRPL grabbers are used on the "Review URL" specified in the Header.
* You MUST include at least one of these grabbers in order to use an RRRP grabber.

Line Name		Notes
-------------------------------------------------------------------------------------------
# Pages Search String	* This string is used to locate the "number of pages" given on the
			  pages of the user review listings
			* This string is used on the first review listing page
# Pages End String	* This string is used to locate the end of the "number of pages"
			  given on the pages of the user review listings
			* This string is used on the first review listing page
# Revs String		* This string is used like a CNTR grabber, counting each review on
			  the last page of the user review listing
(Blank Line)

GRABBER - RRRP
==============
Accepted Variable Types
-----------------------
* DEC

Notes
-----
* You MUST have an INT grabber for Review Count and an RRPL-type grabber for Review
  Responses in order to use an RRRP-type grabber.
* A Review Count grabber that is used in defining the RRRP-type grabber MUST be INT.
* The NGLister interface will "lock" any grabbers referenced by an RRRP-type grabber, when
  the RRRP-type grabber is active.  This ensures that the RRRP-type grabber will have data
  to add.

Line Name			Notes
-------------------------------------------------------------------------------------------
Abbrev. for Review Grabber	* This is the "Abbreviation" line from the GLOBAL section
				  of the Review Count grabber you wish to use
				* If a referenced grabber doesn't exist, the program will
				  reject the def file
Abbrev. for RRPL Grabber	* This is the "Abbreviation" line from the GLOBAL section
				  of the RRPL-type grabber you wish to use
				* If a referenced grabber doesn't exist, the program will
				  reject the def file
(Blank Line)
